home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / lib / mntlib44.zoo / mntlib / purec / INSTALL.SRC < prev    next >
Encoding:
Text File  |  1993-06-17  |  12.5 KB  |  301 lines
  1. MiNT Library for Turbo C / Pure C
  2.  
  3. hohmuth 7 Mar 1993
  4.  
  5. This file describes the build and installation procedure of the MiNT 
  6. library for Turbo C and Pure C for the source distribution.  (If you 
  7. have the binary distribution, see the file INSTALL.BIN.  For notes on 
  8. how to use the library, refer to README.PC)
  9.  
  10. At the end of this file, the procedure for building the binary 
  11. distribution is described.
  12.  
  13. --------------------------------------------------------------------------
  14.  
  15. There are two ways for building the library:  One uses a makefile and 
  16. basically consists of configuring the makefile and hitting `make', the 
  17. other one uses project files and requires a bit of twiddling here and 
  18. there.  Personally, I prefer using the makefile, but I understand that 
  19. not everyone wants to spend a lot of time to set up an appropriate 
  20. environment for Make.
  21.  
  22. --------------------------------------------------------------------------
  23.  
  24. INSTALLATION USING `make'.
  25. --------------------------
  26.  
  27. To use the makefile, you need the following programs:
  28.  
  29. o   The compiler's tools (of course), in particular `pcc.ttp', `pasm.ttp' 
  30.     and `plink.ttp' (resp. for Turbo C: `tcc.ttp', `mas.ttp' and 
  31.     `tlink.ttp').
  32.  
  33. o   GNU Make, version 3.60 or better.  (The makefile needs GNU Make's 
  34.     functionality, so please don't try another Make.)
  35.  
  36. o   A good shell is recommended; if you use Turbo C, a shell is 
  37.     compulsory.  (When using Pure C, you can also let Make execute the 
  38.     programs.)
  39.  
  40.     The Makefile has been written in a way that allows the use of both 
  41.     TOS style shells (those that don't grok Un*x style file names) and 
  42.     Un*x like shells.  However, your shell should support output 
  43.     redirection with ' > file'.
  44.  
  45. o   `cp', `rm' (I recommend those from the GNU file utilities, linked 
  46.     with the MiNT library PL 25 or above; these utilities need to 
  47.     understand file names like "/dev/a/foo" instead of "A:\foo".)  (For 
  48.     Pure C, this is again not compulsory; in this case, we only need it 
  49.     for `make install' and `make clean'.)
  50.  
  51. o   If you use Turbo C, you additionally need `echo', because we have to 
  52.     work around Turbo's missing ARGV capability.
  53.     
  54. o   If you use Turbo C and you _don't_ have the osbind library (see 
  55.     below), you additionally need `awk' because we have to hack the 
  56.     assembler sources for Turbo's assembler MAS.
  57.  
  58. Make sure that Make and your shell both have a sufficiant stack; the 
  59. makefile ist pretty tough!  (If Make and your shell have been linked 
  60. with the MiNT library:  The standard 8 K of stack are not enough!  Try 
  61. to enlarge it with e.g. `fixstk 20K make.ttp'.)
  62.  
  63. When using Turbo C, please note that the link pass (when creating the 
  64. library mintlib.lib) needs a _LOT_ of memory (2.5 MB RAM).  Pure C's 
  65. linker isn't that hungry.
  66.  
  67. The MiNT Library comes with its own sources for TOS bindings.  Optionally, 
  68. you may use any other library of TOS bindings and link that one into the 
  69. MiNT library.  Note, however, that the TOS bindings library of Pure C 
  70. and Turbo C cannot be used for that (they're either incompatible with the 
  71. definitions in `osbind.h' and `mintbind.h', or do not contain bindings for 
  72. MiNT's GEMDOS functions).  As a TOS bindings substitute, the OSBIND 
  73. library by Ole Arndt and Ulf Moeller (version 2 or better) is a good 
  74. choice.
  75.  
  76. If you use Turbo C, building the TOS bindings is non-trivial:  we have to 
  77. hack the sources using `awk', a filter program, because Turbo's assembler 
  78. MAS doesn't understand ".MODULE" and ".ENDMOD".  If you don't have this 
  79. program, I strongly suggest you to get the OSBIND library by Ole Arndt and 
  80. Ulf Moeller.
  81.  
  82. To build the library, the following steps are nessecary.
  83.  
  84. 1)  Edit the `makefile' to suit your taste.  You should only have to edit 
  85.     the configuration section at the beginning of the file.  Simply 
  86.     follow the instructions given as comments in the makefile.  (Comments 
  87.     are on lines starting with `#'.)
  88.     
  89.     Here is a list of Make variables which have to be configured, and 
  90.     their default:
  91.     
  92.     TURBOC=                                 # undefined means "use Pure C"
  93.     COMPILERDIR=    /dev/d/pc               # compiler's dir.
  94.     LIBDIR=         $(COMPILERDIR)/lib      # compiler's lib dir
  95.     COMPILERINCDIR= $(COMPILERDIR)/include  # compiler's include dir
  96.     INCLUDEDIR=     /dev/g/gnu/include      # MiNT lib's include dir
  97.     OSBINDLIB=                  # undef'd means "don't have osbind lib"
  98.     INSTALLDIR=     $(LIBDIR)               # where to install MiNT lib
  99.     COMMONDIR=      ..                      # location of common sources
  100.     ASSERTIONS=                 # undef'd means "make assertions silently"
  101.     DEBUGINFO=                  # undef'd means "don't add debug info"
  102.     PCREL=                      # undef'd means "use absolute calls"
  103.     TOSIFY_NAMES=   yes         # compiler's tools need old style file names
  104.     TOSIFY_COMMAND=             # undef'd means "shell groks Un*x file names"
  105.     sh_backslash=   \\          # bourne shell needs escaped backslashes
  106.     SHELL=          /bin/sh                 # I use a standard Bourne shell
  107.     RM=             rm                      # remove command
  108.     CP=             cp                      # copy command
  109.     AWK=            awk                     # awk interpreter
  110.     ECHO=           echo                    # echo command
  111.     INSTALL_DATA=   cp                      # install command
  112.  
  113.     A somewhat difficult decision is which shell to use.  I use a standard 
  114.     bourne shell (from the BSD networking distribution); Bash (the GNU 
  115.     Bourne Again Shell), Mupfel 1.89 or better (which comes with Gemini) 
  116.     and `shell.ttp' (from the Elvis for MiNT distribution) also work.  
  117.     Mupfel 1.21 will _not_ work.  I haven't tried Gulam, but I presume it 
  118.     works too.  When using Pure C, you could also try specifying no shell 
  119.     at all and have make executing your commands.
  120.     
  121.     Depending on your shell, you need to configure the Make variables 
  122.     SHELL, TOSIFY_COMMANDS and sh_backslash.  Here are the settings for 
  123.     the shells I tried:
  124.     
  125.     sh, bash        sh_backslash = \\
  126.     shell.ttp       sh_backslash = \$(nothing)
  127.     mupfel.ttp      sh_backslash = \$(nothing), TOSIFY_COMMANDS = yes
  128.  
  129. 2)  Copy the files math.h and float.h from your compiler's distribution 
  130.     to the MiNT library's include directory, renaming them to tcmath.h 
  131.     and tcfloat.h.
  132.  
  133.     The following command does this for you:
  134.     
  135.         make install-includes
  136.     
  137. 3)  You're ready to build the library now.  Hit
  138.  
  139.         make
  140.         
  141.     This builds the following files:  mintlib.lib, mintflt.lib, crt0.o 
  142.     and alloca.o.  If you've configured for Pure C, additionally the 
  143.     following files will be built:  mint881.lib and falloca.o.
  144.     
  145. 4)  If you prefer, you can make a quick test of your new library.  The 
  146.     command
  147.     
  148.         make test
  149.     
  150.     links a small test program with the library which, when invoked with 
  151.     `./test', prints out "Hello, world!".
  152.  
  153. 5)  Install the file you've built in step 3 into the appropriate 
  154.     directory by invoking
  155.     
  156.         make install
  157.         
  158. 6)  You are done.  You can clean the source directories with
  159.  
  160.         make clean
  161.         
  162.     which removes all intermediate files, or
  163.     
  164.         make realclean
  165.         
  166.     which additionally removes the libraries you've just built.
  167.  
  168. --------------------------------------------------------------------------
  169.  
  170. INSTALLATION USING PROJECT FILES.
  171. ---------------------------------
  172.  
  173. Environment.
  174.  
  175. 1)  Create a copy of the file pc.cnf (resp. tc.cnf) in this directory, 
  176.     named mintlib.cnf.
  177.  
  178. 2)  Copy the files math.h and float.h from the Pure/Turbo C include 
  179.     directory to the MiNT library include directory, naming them tcmath.h 
  180.     resp. tcfloat.h
  181.  
  182. 3)  Only for Turbo C: 
  183.     =================
  184.  
  185.     o   Comment out the line "falloca.s [-D=STACKCH=1 -D=FPU=1]" in 
  186.         test.prj, and uncomment the line containing "tcstdlib.lib".
  187.  
  188.     o   In mintflt.prj, change the file name pcfltlib.lib to tcfltlib.lib.
  189.  
  190.     o   Comment out pclong.s in mintlib.prj.  (You'll have to link the 
  191.         standard library tcstdlib.lib for long int arithmetics support in 
  192.         your project files.)
  193.  
  194.     o   We want to link bindings for TOS and MiNT functions in the MiNT 
  195.         library.  However, the assembler source files for the bindings 
  196.         are incompatible with Turbo's assembler MAS.  You have two ways 
  197.         to get around this:
  198.  
  199.         a)  Go and find another bindings library and link that one into 
  200.         the MiNT Library.  (Note that the bindings library that comes with 
  201.         Turbo C cannot be used.)
  202.         I strongly suggest you to get the OSBIND library by Ole Arndt and 
  203.         Ulf Moeller.  List osbind.lib in mintlib.prj, and comment out 
  204.         bios, xbios.s, gemdos.s and mintbind.s.
  205.  
  206.         b)  If you choose to build the MiNT library using `make' (see 
  207.         the first section of this file), the make procedure will do the 
  208.         nessecary hacks in the assembler sources using the program `awk'. 
  209.         I do not recommend doing the hacks by hand.
  210.  
  211. 4)  Start C, load mintlib.cnf and set the include directory to the the 
  212.     directory where the MiNT library's include files reside.  In the 
  213.     Options/Shell dialog, turn off "Make breaks on compiler warnings". 
  214.     With Pure C, turning on the compiler caches speeds up the Make 
  215.     procedure dramatically.
  216.     If you want debug information in the libraries, set the compiler 
  217.     switch -Y (Options/Compiler, Options/Assembler and Options/Linker).  
  218.     If you prefer absolute calls to subroutines (useful with large 
  219.     projects), turn -P on, too.
  220.     All other Compiler and Linker switches should be turned off.
  221.  
  222. Make The Floating Point Library.
  223.  
  224. This library contains the float/double support for the compiler as well 
  225. as versions of printf/scanf that support floating point numbers.
  226.  
  227. 5)  Select the project file MINTFLT.PRJ. Make all.
  228.  
  229. 5a) You have to delete the files main.o, doprnt.o, scanf.o, difftime.o 
  230.     and purec/setjmp.o now.  These files have to be recompiled with the 
  231.     Line-F support (step 6) and the main part of the MiNT library 
  232.     (step 7).
  233.  
  234. Make The Line-F Support Library. (Pure C only)
  235.  
  236. This library contains actually the same as the floating point library, 
  237. plus support for programs that use a FPU directly via Line-F.
  238.  
  239. 6)  Only for Pure C:
  240.     ================
  241.     Repeat steps 5 and 5a with MINT881.PRJ.
  242.  
  243. Make The MiNT Library.
  244.  
  245. 7)  Select the project file MINTLIB.PRJ. Make all.
  246.     This step takes a while (around 15 minutes with Pure C and an 8MHz 
  247.     ST).
  248.  
  249. Compile The Startup Code And The Assembler Version Of alloca();
  250. Test The Libraries.
  251.  
  252. 8)  Select the project file TEST.PRJ. Make all.
  253.     This compiles the startup code and the assembler versions of alloca(), 
  254.     and links a test program.
  255.     
  256.     (Pure C: You get a linker warning "Doubly defined symbol: 'alloca'" 
  257.     because alloca.s and falloca.s both define a symbol `alloca'.  Ignore 
  258.     it.)
  259.  
  260. 9)  Run. You should get a "Hello, world." message.
  261.  
  262. Install The Libraries.
  263.  
  264. 10) Copy the files crt0.o, alloca.o, mintlib.lib, mintflt.lib, falloca.o 
  265.     and mint881.lib (the last two are Pure C only) to the directory you 
  266.     want them to reside.
  267.  
  268. --------------------------------------------------------------------------
  269.  
  270. HOW TO BUILD THE BINARY DISTRIBUTION.
  271. -------------------------------------
  272.  
  273. The library binaries mintflt.lib and mint881.lib, when built with the 
  274. setup as shipped, will contain Turbo/Pure C's math library binaries.  
  275. These binaries should not be made available to the public.  If you want 
  276. to create a binary distribution, you should build library binaries which 
  277. don't contain the compiler's libraries.
  278.  
  279. To do this, the following steps are nessecary:
  280.  
  281. 1)  Set up the makefile as described in the section "INSTALLATION USING 
  282.     `make'", step 1.
  283.     
  284. 2)  Copy the compiler's math include as described in the same section, 
  285.     step 2. (`make install-includes')
  286.  
  287. 3)  The command
  288.  
  289.         make bindist
  290.  
  291.     will then create the files mintlib.lib, d_flt.lib, crt0.o and     
  292.     alloca.o.  If you've configured for Pure C, additionally the 
  293.     following files will be built:  d_881.lib and falloca.o.
  294.  
  295. The files you've just built can be freely distributed, along with 
  296. `makefile', `tosify.mak' (these two from the source distribution) and 
  297. 'INSTALL.BIN', the last describing how to build the mintflt.lib and 
  298. mint881.lib binaries from that distribution.
  299.  
  300.  
  301.